home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / ai / nrlibe32 / nrlib32.txt < prev    next >
Text File  |  1994-11-30  |  19KB  |  554 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                  ROUTINES LIBRARY
  11.                    FOR
  12.             MULTIPLE NEURAL NETWORKS MANAGEMENT
  13.  
  14.  
  15.                  (for C programs)
  16.  
  17.  
  18.                    Version 3.2
  19.  
  20.            Copyright (C) 1994 by Daniele Denaro
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31. Daniele Denaro                          Internet :
  32. Via Sergio Forti , 47                   Mail: daniele@caio.irmkant.rm.cnr.it
  33. 00144 - ROMA (ITALY)                    ftp anonymous : kant.irmkant.rm.cnr.it
  34. Tel. 39-6-5292189                                    pub/source/nrlib
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.                    INDEX
  43.  
  44.  
  45.  
  46.     1.      - Introduction                  3
  47.     2.      - Neural network architecture   4
  48.         2.1- Structure                  4
  49.         2.2- Activation functions       6
  50.         2.3- User activation functions  7
  51.     3.      - Functions list                8
  52.     4.      - Example of library use        10
  53.     5.      - File format of nets saving    11
  54.     6.      - NREBP program                 12
  55.     7.      - Version 4 enhancements        13
  56.  
  57.  
  58.  
  59.  
  60. 1 - Introduction
  61.  
  62. This package contains a shell for neural networks real applications.
  63. NRLIB32 and NREBP32 are shareware programs. You can use them to test and
  64. verify their functionality. If you will be satisfied register you using form
  65. in "readme.txt" file.
  66. NRLIB32 is a software library and NREBP32 a companion program.
  67. This software was developped in C language and is available for any
  68. computer; but in this package is also provided compiled version for 286->486
  69. PC systems (with math. coprocessor).
  70.  
  71. This library provide 50 functions for manage multiple neural networks in C
  72. programs.
  73. We can :
  74.  - Create in memory one or more nets (different too).
  75.  - Save and load all nets on/from a file
  76.  - Net compute (input propagate)
  77.  - Net train with EBP (Error Back Propagation)
  78.  or many other manipulations.
  79.  
  80. Each net can have any number of layers (to 100 layers).
  81. Each layer can have any number of nodes.
  82. Each node can have any number of links with others nodes.
  83.  
  84. The nodes have progressive number in a net.
  85. You can choose a different activation function for each node.
  86. There are ten types of activation function : 6 defined and 3 for user
  87. definition.
  88. For each node it's also possible to define another function named action,
  89. which is called after the activation function.
  90.  
  91. Range of principals values:
  92. - Net number    1 -- 1000 (in this release)
  93. - Layer number  0 -- 99
  94. - Node number   1 -- 7FFFFFFF (in hex)
  95.  
  96. Files included in the package:
  97.  
  98. - README.TXT    Abstract and orders details
  99. - NRLIB32.H     Include file for library use. Funct. are descr.like in a manual.
  100. - NRLIB32.OBJ   Object file that you must link with your program .
  101. - NRLIB32.C     Library source
  102. - NREBP32.EXE   Complete program (interactive) for EBP net use
  103. - NREBP32.C     Source of NREBP32
  104. - EXAMPLE1.C    Example 1 of NRLIB32 use (imitation metaphor)
  105. - EXAMPLE2.C    Example 2 of NRLIB32 use (genetic algoritm)
  106. - EXAMPLE1/2.EXE   (compiled versions)
  107. - NRLIB32.PS            This document in postscript
  108. - NRLIB32.TXT           "            in ASCII format (without figures)
  109. - NETTRAIN.DAT  Trainer file for XOR task
  110. - NNETSINP.DAT  Example of nets save file
  111. - NNETXOR.DAT   Example of nets save file (trained on XOR task)
  112.  
  113.  
  114. 2 - Neural network architecture
  115.  
  116. 2.1 - Structure
  117.  
  118. A neural network is a logical structure composed by lots of nodes (neurons)
  119. and by links (synapses) between them.
  120. Nodes accept inputs from other nodes or external environment , and propagate
  121. this sum to linked nodes . Input propagation is filtered by a saturation
  122. function called activation function and by a scaling factor that corresponds
  123. to the weight of a particular link .
  124.  
  125. Links structure and weights values identify the net behaviour , i.e. the
  126. status of output nodes as answer of a stimulus on input nodes. Identified
  127. the proper architecture , we can modify the weights to train a net to the
  128. behaviour selected.
  129.  
  130. For more details on neural network architecture theory and training methods
  131. , we remand to specialized literature.
  132.  
  133. This library allows to define any neural net architecture, but the macro-
  134. functions for net management are made for a forward layered net, to be
  135. trained with EBP (Error Back Propagation) rule.
  136.  
  137. The principal characteristic of this library is that it uses a sequential
  138. list of nodes with their parameters  (i.e. input , status , pointer to
  139. activation function , pointer to links  etc.), and a sequential list of all
  140. links; this structure allow flexibility , computing speed and memory
  141. optimisation at the same time.
  142. For this reason each node can have different activation function or
  143. different bias as well as different links number.
  144.  
  145.  
  146.  
  147.  
  148. Over this organization there is another  lists structure. This structure
  149. allows to describe the whole of nets ; moreover it logically organize the
  150. net nodes in layers.
  151. Pointers are often used for more quickness.
  152. Memory is dinamically allocated to according nets dimension and
  153. availability.
  154.  
  155.  
  156. In theory, layers information can be  ignored , because the original net
  157. structure in memory dasn't need layers information to run along the net.
  158. But, even if  there are routines for single node access and manipulation ,
  159. more helpful routines are provide for use in forward nets with layers
  160. organization . In fact , forward propagation of input and EBP training
  161. functions are made for multilayered forward nets.
  162.  
  163. Therefore a net is typically organized in layers. First layer is layer 0 and
  164. corresponds to net input. It is possible to have up to 100 layers (last
  165. layer = 99). Last layer correspond to net output.
  166.  
  167. If we want  the net answer to an input stimulus, we must copy input values
  168. (in normalized floating format) to input buffer of input nodes , and , after
  169. net computing , we can receive output answer on reading status buffer of
  170. output nodes.
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179. Net creation routines require an array of values for each node
  180. characteristic .  Each value is valid for all nodes of a layer , i.e. all
  181. nodes of a layer are created equals. And each node is linked with each node
  182. of next layer. Node bias are 0 for default and links weights are randomicaly
  183. assigned , but you can modify them by single node functions if need it.
  184.  
  185. In the net elaboration phase , input node buffer is modified by the
  186. activation function and the result is put in status  node buffer (also
  187. called activation).
  188.  
  189.  
  190.  
  191. 2.2 - Activation functions
  192.  
  193. There are 6 types of activation function provided by the library. The
  194. principals are:
  195. - Linear funct. (simply move input to status): name f1 (useful for input nodes)
  196. - Positive/negative  sigmoid                 : name f3 (by table) or f13 (calculated)
  197. - Only positive sigmoid                      : name f5 (by table) or f15 (calculated)
  198.                             
  199.                             1:   --
  200.        :   /                1 :   _                  : /
  201.        : /   f1               : /   f3=f13           /     f5=f15
  202.       ...........            ...........               / :    
  203.       /:                     /:                -- .........
  204.     /  :                   -  :-1                    :
  205.  
  206. Functions f3 and f5 are realized by look table , with 0.01 precision , for
  207. more speedness.
  208. Also their derivatives are realized by look table.
  209. Functions f13 and f15 (and their derivatives) are calculated in simple
  210. precision ,for more accuracy.
  211. Names are transformed in pointers  on creating or loading net in memory.
  212. Other four function names (f7,f8,f9,f10) are recognized but are provided by
  213. user if needed (see next paragraph for more details).
  214. Function f2,f4,f6 have been holded for compatibility with previous version
  215. and can be seen as reserved names .
  216.  
  217. In addiction , we can define another function for a node. This function is
  218. called "action" in this library and can be used for more sophisticated
  219. applications as a Hebs training rule for example.
  220. This function is user provided and the names recognised are a1 -- a6.
  221. If  function name is "0" or an unknown name , it is ignored in node
  222. computing.
  223. If it is defined, it is valuated after activation function.
  224.  
  225. Net training  is usually performed by EBP rule. Library routines for this
  226. purpose are very simple to use. They start with a difference < out
  227. calculated - out expected>  loaded in error node buffer of last layer and
  228. back propagate error to first layer on correcting links weights at the same
  229. time.
  230. For back error propagation they use correspondent derivative of activation
  231. function present on each node .
  232.  
  233.  
  234.  
  235.  
  236. 2.3 - User activation function
  237.  
  238. As described in previous paragraph, names allowed are: f7,f8,f9,f10 .
  239. They are defined in NRLIB32.H file as null functions.
  240. If user want, he may to redefine this functions in this file or in his
  241. program.
  242.  
  243. User activation functions have four parameeters:      ex. f7(int net,LONG
  244. nn, int f,float *d)
  245.  - net number
  246.  - node number
  247.  - flag function/derivative (0 function , 1 derivative )
  248.  - pointer to derivative return value buffer
  249.  
  250. Activation functions are called by library function for forward phase and
  251. back propragation phase.
  252. For this reason flag is used to distinguish between forward (normal) phase
  253. and back propagation phase. In forward phase , activation function is used
  254. to modify input  and put result in status for each node with this function.
  255. In back propagation phase, derivative is instead used as returned value in
  256. buffer d.
  257.  
  258. In other words, if function is called with flag f = 0 , we must modify node
  259. input , write result in node status and blank node input (for next cicle) ;
  260. this is forward computation.
  261. If function is called with flag f = 1, we must calculate activation function
  262. derivative for actual status value  (we must determine derivative in
  263. function of status value because in back propagation phase node input is
  264. inavaillable ; it has been blanked in forward phase).
  265. If you don't use Error Back Propagation algoritm you can put 0 on derivative
  266. buffer.
  267.  
  268. Definition example :
  269. Saturation : y=1- e-x   dy/dx = e-x = 1- y
  270.  
  271. f7(int net , LONG nn , int f, float *d)
  272. {
  273.    float buff;
  274.    if (f == 0) { rinp(net, nn, &buff);        /* read node input  (rinp :
  275. library function)  */
  276.              buff=1-exp(-buff) ;          /* modify input */
  277.              wstat(net, nn, buff);         /* write node status
  278. (wstat : library function) */
  279.              winp(net, nn, 0);              /* blank node input
  280. (winp : library function)  */
  281.              return ; }
  282.     if (f == 1) {rstat(net,nn,buff);           /* read node status (rstat :
  283. library function) */
  284.              *b = 1- buff ;                 /* derivative value */
  285.               return ; }
  286. }
  287.  
  288. Action functions (a1 -- a6) have instead two parameters : net number and
  289. node number ; and have free definition.
  290.  
  291.  
  292.  
  293. 3 - Functions list
  294.  
  295. For details on functions and their parameters you can see the NRLIB32.H
  296. file, where they are described .
  297.  
  298. Load and save nets :
  299.    loadnet (char *fileinp);
  300.    savenet (char *fileout);
  301.  
  302. Create nets :
  303.    createstruct ( tn, vlay[]);
  304.    createnet ( net,LONG vn[],char vf[][10],char va[][10]);
  305.  
  306. Create all equals nets :
  307.    createallnet ( tn, nlay,LONG vn[],char vf[][10],char va[][10]);
  308.  
  309. Reinitialise net :
  310.    ininet ( net);
  311.  
  312. Copy net to net:
  313.    copynet ( nta, ntb);
  314.  
  315. Release memory allocated for nets :
  316.    cancnets ();
  317.  
  318. Modify global parameters :
  319.    param (char *name, char *val);
  320.  
  321. Compute net :
  322.    produce ( net,char *finpdat, char *foutdat);
  323.    compute ( net,float vinp[],float vout[],float vdat[]);
  324.    propagate ( net, laya, layb);
  325.  
  326. Train net :
  327.    train ( net,char *filetrain);
  328.    learn ( net,float verr[]);
  329.    backprop ( net, laya, layb);
  330.    backproperr ( net, laya, layb);
  331.    cancerr ( net, laya, layb);
  332.  
  333.  
  334.  
  335.  
  336. Read or modify nets parameters:
  337.    rmnet ( *totnet);
  338.    wmnet ( totnet);
  339.    rmlay ( net, *mlay);
  340.    totnn ( net, LONG *tnode);
  341.    wmlay ( net, mlay);
  342.    rlay ( net, nlay,LONG *sn,LONG *en);
  343.  
  344. Read or modify nodes parameters of a layer :
  345.    rstatl ( net, nlay,float stat[], dim);
  346.    wstatl ( net, nlay,float stat[], dim);
  347.    rinpl ( net, nlay,float inp[], dim);
  348.    winpl ( net, nlay,float inp[], dim);
  349.    rerrl ( net, nlay,float err[], dim);
  350.    werrl ( net, nlay,float err[], dim);
  351.    rbiasl ( net, nlay,float bias[], dim);
  352.    wbiasl ( net, nlay,float bias[], dim);
  353.    rwgtl ( net,LONG nn, nlayp,float wgt[], dim);
  354.    wwgtl ( net,LONG nn, nlayp,float wgt[], dim);
  355.    rwgtil ( net,LONG npp, nlaya,float wgt[], dim);
  356.    wwgtil ( net,LONG npp, nlaya,float wgt[], dim);
  357.  
  358. Read or modify single node parameters :
  359.    rstat ( net,LONG nn,float *stat);
  360.    rbias ( net,LONG nn,float *bias);
  361.    rinp ( net,LONG nn,float *inp);
  362.    rerr ( net,LONG nn,float *err);
  363.    rfun ( net,LONG nn,char fun[10],char ac[10]);
  364.    wstat ( net,LONG nn,float stat);
  365.    winp ( net,LONG nn,float inp);
  366.    werr ( net,LONG nn,float err);
  367.    wbias ( net,LONG nn,float bias);
  368.    wfun ( net,LONG nn,char fun[10],char ac[10]);
  369.    rnconn ( net,LONG nn,LONG *ncl);
  370.    rconn ( net,LONG nn,LONG cl,float *wgt ,LONG *np);
  371.    wwgt ( net,LONG nn,LONG cl,float wgt);
  372.    wnodp ( net,LONG nn,LONG cl,LONG np);
  373.    wnconn ( net,LONG nn,LONG ncl);
  374.  
  375.  
  376. Version 3.2 differs from version 3.1 by bugs corrections in functions rwgtl and
  377. wwgtl ; and activation functions f13 and f15 added
  378.  
  379.  
  380.  
  381. 4 - Example of library use
  382.  
  383.                                (f5)       layer 2
  384.                               /  |  \
  385. Imagine that we wont to define a net                /    |    \
  386. of 3 layers as described in  picture.             (f5) (f5) (f5)  layer 1
  387.                           \   \/ \/   /
  388. We must include NRLIB32.H file and                  \/  /\ \/
  389. link our program with NRLIB32.OBJ. For              (f1)  (f1)    layer 0
  390. DOS system memory model is large.
  391.  
  392.  
  393. Define array for number nodes , activation function and action function for each
  394. layer:
  395.   LONG vn[3];char vf[3][10], va[3][10];
  396. and initialize it
  397.   vn[0]=2; strcpy(vf[0],"f1"); strcpy(va[0],"0");   layer 0 : 2 nodes with linear
  398. activation
  399.   vn[1]=3; strcpy(vf[1],"f5"); strcpy(va[1],"0");   layer 1 : 3 nodes with sigmoid
  400. activation
  401.   vn[2]=1; strcpy(vf[2],"f5"); strcpy(va[2],"0");   layer 2 : 1 node with sigmoid
  402. activation
  403. now create net
  404.    createallnet(1,2,vn,vf,va)   single net with maximum layer 2 ;
  405.                 each layer characteristics done by arrays vn,vf,va
  406. or (alternative way)
  407.     int vlay[2];     define array of maximum layer of each net
  408.     vlay[1]=2;      maximum layer of net 1 (vlay[0] is not used)
  409.     createstruct(1,vlay);        define structure that describe only one net
  410.     createnet (1,vn,vf,va);     create net 1 of structure
  411.  
  412. Suppose that we wont to trainer this net to learn XOR function, and save net
  413. trained.
  414.  
  415.      param("ne","1000");         define 1000 epocs for training
  416.      train(1,"nnetxor.dat");       train net 1 with trainer file "nnetxor.dat"
  417.  
  418. File nnetxor.dat contain records with various input-ouput coupled according to XOR
  419. function.
  420.  
  421. Save net trained, on file "xorout.dat"
  422.       savenet("xorout.dat");
  423.  
  424. If we wont to reuse this trained net in another program we can load it simply.
  425.       loadnet("xorout.dat");
  426.  
  427. And use it as a filter function
  428.       produce(1,"fileinp.dat","fileout.dat");
  429.  
  430. Where fileinp.dat contain input values and fileout is writed by net answers.
  431.  
  432.  
  433.  
  434. 5 - File format of nets saving
  435.  
  436.  
  437. First record
  438.     "totnets"/max_net_num/total_layers/
  439. Other record
  440.     "nnet"/net_num/total_nodes/total_links/
  441. or
  442.     "lay"/layer_num/
  443. or
  444.     "node"/node_num/input/bias/stat/fun_name/ac_name/
  445. or
  446.     "conn"/pointed_node;weigth/...../pointed_node;weigth/
  447.  
  448.  
  449. example :
  450.  
  451.     totnets/1/3/
  452.  
  453.     nnet/1/6/9/
  454.     lay/0/
  455.       node/1/0.0000/0.0000/0.0000/f1/*/
  456.         conn/3;-0.3916/4;-0.3968/5;-0.1319/
  457.       node/2/0.0000/0.0000/0.0000/f1/*/
  458.         conn/3;-0.3734/4;-0.1154/5;-0.2262/
  459.     lay/1/
  460.       node/3/0.0000/0.0000/0.0000/f5/*/
  461.         conn/6;0.0296/
  462.       node/4/0.0000/0.0000/0.0000/f5/*/
  463.         conn/6;-0.2434/
  464.       node/5/0.0000/0.0000/0.0000/f5/*/
  465.         conn/6;0.1603/
  466.     lay/2/
  467.       node/6/0.0000/0.0000/0.0000/f5/*/
  468.         conn/
  469.  
  470.  
  471.  
  472.    - it's possible to continue record on more lines
  473.    - each field ends with / character
  474.    - input,bias,status,weigt are float , other integer
  475.    - fun_name and ac_name are strings
  476.  
  477.  
  478.  
  479. 6 - NREBP program
  480.  
  481. NREBP program is included in the package. This program is an interactive software
  482. that allows us to create or load one or more nets and activate or train them.
  483.  
  484. It has 3 way of using :
  485. - like a filter
  486. - interactive nets management
  487. - batch train
  488.  
  489. The 3 modalities are decided by parameeter fu (fu = 0,1,2).
  490.  
  491. In the first use , it receives an input from standard input and evaluates a net
  492. producing an output on standard output. This is the default functionality.
  493. At starting phase , it load nets from default nets file or user provided file.
  494.  
  495. For example , if command is :
  496.  
  497. NREBP32   /fu=0  <stimul.dat  >results.dat      (or NREBP32  <stimul.dat >result.dat)
  498.  
  499. it load nets from default nnetsinp.dat  and  activate net 1 with input read from
  500. file stimul.dat and write output to file results.dat.
  501.  
  502. In the second use , it appears as menu driven software. It allow us to create or
  503. load nets , compute or train them  and  save nets to a file.
  504. Interactive interface dasn't need grafic device but simply text line device with
  505. ANSI escape control characters, for better software portability.
  506.  
  507. Example of command :
  508.  
  509. NREBP32   /fu=1
  510.  
  511. To testing this program, net definition file "nnetsinp.dat"  and trainer file
  512. "nettrain.dat", for XOR task, are included in package. You can load net and train
  513. it. Or you can load trained net by "nnetxor.dat" file, and verify corrects answers.
  514.  
  515. Third use allows us to train a nets in batch mode for a set number of epochs .
  516.  
  517. For example, if command is:
  518.  
  519. NREBP32   /fu=2  /ne=5000
  520.  
  521. it loads nets from default file nnetsinp.dat and trains net 1 reading trainer file
  522. nettrain.dat for 5000 times; then it writes last averege quadratic error and saves
  523. nets to default file nnetsout.dat.
  524. For more details ask help typing :  NREBP32   /h
  525.  
  526.  
  527. 7 - Version 4 enhancements
  528.  
  529. This version is already available ;  for any request contact  me (see file
  530. README.TXT).
  531. Functions available increase to 59.
  532. More complex logic structure is definable for a net.
  533. With simple routines like "createnet", "compute", "learn" etc. , we can
  534. manage net with memory contest layer or recursive layer.
  535.  
  536. Each layer  can be linked with more layers (to 10) , no more with following
  537. layer only.
  538. Each layer can have a pointer to a layer  that realize a memory contest.
  539. Each layer can have a pointer to a layer that realize a duplicated layer.
  540.  
  541. Before starting compute phase , library routine, copies nodes status of a
  542. layer to input buffer of  the contest memory layer correspondent.
  543. For layer duplicated , compute routine , copies nodes status of  the layer
  544. to the nodes status of  layer duplicated at the same time when compute it.
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.